=begin pod :kind("Type") :subkind("role") :category("composite")

=TITLE role Iterable

=SUBTITLE Interface for container objects that can be iterated over

    role Iterable { }

C<Iterable> serves as an API for objects that can be iterated with
C<for> and related iteration constructs, like assignment to a
C<Positional> variable.

C<Iterable> objects nested in other C<Iterable> objects (but not within
scalar containers) flatten in certain contexts, for example when passed
to a slurpy parameter (C<*@a>), or on explicit calls to C<flat>.

Its most important aspect is a method stub for C<iterator>.

=begin code
class DNA does Iterable {
    has $.chain;
    method new ($chain where { $chain ~~ /^^ <[ACGT]>+ $$ / } ) {
        self.bless( :$chain );
    }

    method iterator(DNA:D:) {
        $!chain.comb.rotor(3).iterator;
    }
}

my $a := DNA.new('GAATCC');
.say for $a; # OUTPUT: «(G A A)␤(T C C)␤»
=end code

This example mixes in the Iterable role to offer a new way of iterating
over what is essentially a string (constrained by
L<C<where>|/type/Signature#index-entry-where_clause> to just
the four DNA letters). In the last statement, C<for> actually hooks to
the C<iterator> role printing the letters in groups of 3.

=head1 Methods

=head2 method iterator

Defined as:

    method iterator(--> Iterator:D)

Method stub that ensures all classes doing the C<Iterable> role have a
method C<iterator>.

It is supposed to return an L<Iterator|/type/Iterator>.

    say (1..10).iterator;

=head2 method flat

Defined as:

    method flat(Iterable:D: --> Iterable)

Returns another L<Iterable|/type/Iterable> that flattens out all iterables that
the first one returns.

For example

    say (<a b>, 'c').elems;         # OUTPUT: «2␤»
    say (<a b>, 'c').flat.elems;    # OUTPUT: «3␤»

because C<< <a b> >> is a L<List|/type/List> and thus iterable, so C<<
(<a b>, 'c').flat >> returns C<('a', 'b', 'c')>, which has three elems.

Note that the flattening is recursive, so C<((("a", "b"), "c"),
"d").flat> returns C<("a", "b", "c", "d")>, but it does not flatten
itemized sublists:

    say ($('a', 'b'), 'c').raku;    # OUTPUT: «($("a", "b"), "c")␤»

You can use the L«hyper method call|/language/operators#index-entry-methodop_>>.» to
call the L«C<.List>|/routine/List» method on all the inner itemized sublists
and so de-containerize them, so that C<flat> can flatten them:

    say ($('a', 'b'), 'c')>>.List.flat.elems;    # OUTPUT: «3␤»

=head2 method lazy

Defined as:

    method lazy(--> Iterable)

Returns a lazy iterable wrapping the invocant.

    say (1 ... 1000).is-lazy;      # OUTPUT: «False␤»
    say (1 ... 1000).lazy.is-lazy; # OUTPUT: «True␤»

=head2 method hyper

Defined as:

    method hyper(Int(Cool) :$batch = 64, Int(Cool) :$degree = 4)

Returns another Iterable that is potentially iterated in parallel, with
a given batch size and degree of parallelism.

The order of elements is preserved.

    say ([1..100].hyper.map({ $_ +1 }).list);

Use C<hyper> in situations where it is OK to do the processing of items
in parallel, and the output order should be kept relative to the input
order. See L«C<race>|/routine/race» for situations where items are
processed in parallel and the output order does not matter.

=head3 Options degree and batch

The C<degree> option (short for "degree of parallelism") configures how
many parallel workers should be started. To start 4 workers (e.g. to use
at most 4 cores), pass C<:4degree> to the C<hyper> or C<race> method.
Note that in some cases, choosing a degree higher than the available CPU
cores can make sense, for example I/O bound work or latency-heavy tasks
like web crawling. For CPU-bound work, however, it makes no sense to
pick a number higher than the CPU core count.

The C<batch> size option configures the number of items sent to a given
parallel worker at once. It allows for making a throughput/latency
trade-off. If, for example, an operation is long-running per item, and
you need the first results as soon as possible, set it to 1. That means
every parallel worker gets 1 item to process at a time, and reports the
result as soon as possible. In consequence, the overhead for
inter-thread communication is maximized. In the other extreme, if you
have 1000 items to process and 10 workers, and you give every worker a
batch of 100 items, you will incur minimal overhead for dispatching the
items, but you will only get the first results when 100 items are
processed by the fastest worker (or, for C<hyper>, when the worker
getting the first batch returns.) Also, if not all items take the same
amount of time to process, you might run into the situation where some
workers are already done and sit around without being able to help with
the remaining work. In situations where not all items take the same time
to process, and you don't want too much inter-thread communication
overhead, picking a number somewhere in the middle makes sense. Your aim
might be to keep all workers about evenly busy to make best use of the
resources available.

You can also check out this
B«L<blog post on the semantics of hyper and race|https://6guts.wordpress.com/2017/03/16/considering-hyperrace-semantics/>»

=head2 method race

Defined as:

    method race(Int(Cool) :$batch = 64, Int(Cool) :$degree = 4 --> Iterable)

Returns another Iterable that is potentially iterated in parallel, with a
given batch size and degree of parallelism (number of parallel workers).

Unlike L«C<hyper>|/routine/hyper», C<race> does not preserve the order of
elements (mnemonic: in a race, you never know who will arrive first).

    say ([1..100].race.map({ $_ +1 }).list);

Use race in situations where it is OK to do the processing of items in parallel,
and the output order does not matter. See L«C<hyper>|/routine/hyper» for
situations where you want items processed in parallel and the output order
should be kept relative to the input order.

B«L<Blog post on the semantics of hyper and race|https://6guts.wordpress.com/2017/03/16/considering-hyperrace-semantics/>»

See L«C<hyper>|/routine/hyper» for an explanation of C<:$batch> and C<:$degree>.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
